Option Explicit


'################################################################
' Property
'################################################################
' 获取当前一维数据对象中的数据类型
Public Property Get DataType() As DF_DataType
End Property

' 获取当前一维数据对象中的数据数量
Public Property Get Size() As Long
End Property

' 返回当前数据对象所使用的数据类型处理器
Public Property Get TypeHandler() As IDFDataTypeHandler
End Property

'################################################################
' unsafe Function
' 内置加速方法，为了防止异常，在外部如果没有完善的检测机制不应该主动调用
'################################################################
' 内置取值方法
' 将不会对索引范围进行检查
Public Function unsafeGetData(ByRef index As Long) As Variant
End Function

' 内置设值方法
' 将不会对索引范围进行检查
' 将不会对数据进行标准化处理
Public Sub unsafeSetData(ByRef index As Long, ByRef val As Variant)
End Sub

'################################################################
' Function
'################################################################
'--------------------------------------------------
' 缓存回收
'--------------------------------------------------
Public Sub cacheCollect()
End Sub

'--------------------------------------------------
' 数据读写
'--------------------------------------------------

' 检查索引是否在安全范围内
' @param index 需要检查的索引
' @return Boolean True 在安全范围内; False 在有效范围外
Public Function hasIndex(ByRef index As Long) As Boolean
End Function

' 获取指定索引位置的数据
' 如果指定位置没有数据，则默认返回 Empty
'
' @param index 数据索引
' @return 指定索引位置上的数据
Public Function getData(ByRef index As Long) As Variant
End Function

' 设置指定索引位置的数据
'
' 整型数字 DF_INT 返回 Long 或 Integer 型
' 日期 DF_DATE 返回字符串类型
' 时间 DF_TIME 返回字符串类型
' 时间戳 DF_TIMESTAMP 返回字符串类型
'
' @param index 数据索引
' @param val 需要设置的数据
Public Sub setData(ByRef index As Long, ByRef val As Variant)
End Sub

'--------------------------------------------------
' CRUD
'--------------------------------------------------

' 向末尾新增一个数据
'
' @param val 需要设置的数据
Public Sub appendData(ByRef val As Variant)
End Sub

' 向末尾新增一个或多个空数据
'
' @param count 需要添加的空数据的数量，默认=1
Public Sub appendEmpty(Optional ByRef count As Long = 1)
End Sub

' 删除指定索引位置的数据。只删除当前对象内的数据
' 该方法会导致内部数据产生移动，如果数据量很大，将会花费大量时间
'
' @param index 数据索引
Public Sub delData(ParamArray indexes() As Variant)
End Sub

' 删除指定索引位置的数据。只删除当前对象内的数据
' 该方法会导致内部数据产生移动，如果数据量很大，将会花费大量时间
'
' @param index 数据索引
Public Sub delDataByIndexArray(ByRef indexes As Variant)
End Sub

' 删除指定索引位置的数据。如果当前是引用对象，也会直接删除原始对象中的数据
' 该方法会导致内部数据产生移动，如果数据量很大，将会花费大量时间
'
' @param index 数据索引
Public Sub deepDelData(ParamArray indexes() As Variant)
End Sub

' 删除指定索引位置的数据。如果当前是引用对象，也会直接删除原始对象中的数据
' 该方法会导致内部数据产生移动，如果数据量很大，将会花费大量时间
'
' @param index 数据索引
Public Sub deepDelDataByIndexArray(ByRef indexes As Variant)
End Sub

' 拷贝指定索引的数据到末尾
'
' @param index 数据索引
' @optional-param needDescriptor 如果数据存在描述符，是否需要拷贝，默认=False
Public Sub copyAndAppend(ByRef index As Long, Optional ByRef needDescriptor As Boolean=False)
End Sub

' 使用指定数据填充内部所有数据是 Empty 的槽位
'
' 如果参数 val 无法被标准化为与当前 IDFSeries 类型相同的数据，将不会进行数据填充
'
' 对于切片类型，应该只填充引用的那些槽位，未引用的槽位不应该进行修改
'
' @param val 用来填充的数据
Public Sub fillEmptySlot(ByRef val As Variant)
End Sub
'--------------------------------------------------
' 数据计算
'--------------------------------------------------
'===========
' 基础类型计算
'===========
' 对所有数据进行指定方式的运算
'
' @param funcStr 运算函数名字符串
'        需要提供形式为 Function method(ByRef origin As Variant) As Variant 的方法
Public Sub exec(ByRef funcStr As String)
End Sub

' 对所有数据进行指定方式的运算
'
' @param v 运算数据
' @param funcStr 运算函数名字符串
'        需要提供形式为 Function method(ByRef origin As Variant, ByRef computeVal As Variant) As Variant 的方法
Public Sub compute(ByRef v As Variant, ByRef funcStr As String)
End Sub

' 对所有数据进行加法运算
'
' 整型，做加法
' 浮点型，做加法
' 字符串，将会直接做字符串连接
' 日期，以天为单位做加法
' 时间，以秒为单位做加法
' 时间戳，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 布尔型，将不会做处理，如果有需要请使用 compute 或 exec 方法
'
' @param v 运算数据
Public Sub add(ByRef v As Variant)
End Sub

' 对所有数据进行减法运算
'
' 整型，做减法
' 浮点型，做减法
' 字符串，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 日期，以天为单位做减法
' 时间，以秒为单位做减法
' 时间戳，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 布尔型，将不会做处理，如果有需要请使用 compute 或 exec 方法
'
' @param v 运算数据
Public Sub subtract(ByRef v As Variant)
End Sub

' 对所有数据进行乘法运算
'
' 整型，做乘法
' 浮点型，做乘法
' 字符串，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 日期，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 时间，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 时间戳，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 布尔型，将不会做处理，如果有需要请使用 compute 或 exec 方法
'
' @param v 运算数据
Public Sub multiply(ByRef v As Variant)
End Sub

' 对所有数据进行除法运算
'
' 整型，做除法
' 浮点型，做除法
' 字符串，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 日期，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 时间，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 时间戳，将不会做处理，如果有需要请使用 compute 或 exec 方法
' 布尔型，将不会做处理，如果有需要请使用 compute 或 exec 方法
'
' @param v 运算数据
Public Sub divide(ByRef v As Variant)
End Sub

'===========
' 和其他 Series 类型做计算
'===========
' 和其他 Series 做加法运算，计算结果合并到当前 Series
'
' @param desc 运算 Series
Public Sub mergeAdd(ByRef desc As Series)
End Sub

' 和其他 Series 做减法运算，计算结果合并到当前 Series
'
' @param desc 运算 Series
Public Sub mergeSubtract(ByRef desc As Series)
End Sub

' 和其他 Series 做乘法运算，计算结果合并到当前 Series
'
' @param desc 运算 Series
Public Sub mergeMultiply(ByRef desc As Series)
End Sub

' 和其他 Series 做除法运算，计算结果合并到当前 Series
'
' @param desc 运算 Series
Public Sub mergeDivide(ByRef desc As Series)
End Sub

'--------------------------------------------------
' 比较运算
'--------------------------------------------------
'=============
' 生成 Boolean IDFSeries
'=============
' 和指定运算符进行比较，返回一个和当前 series 相同的 Boolean 型的 series
' =
Public Function eq(ByRef v As Variant) As IDFSeries
End Function

' !=
Public Function ne(ByRef v As Variant) As IDFSeries
End Function

' >
Public Function gt(ByRef v As Variant) As IDFSeries
End Function

' <
Public Function lt(ByRef v As Variant) As IDFSeries
End Function

' >=
Public Function ge(ByRef v As Variant) As IDFSeries
End Function

' <=
Public Function le(ByRef v As Variant) As IDFSeries
End Function

' In()
Public Function inVals(ByRef vs As Variant) As IDFSeries
End Function

' between
Public Function between(ByRef left As Variant, ByRef right As Variant) As IDFSeries
End Function

'=============
' 生成 Series ，保存所有结果为 true 的数据
'=============
' =
Public Function eqToSeries(ByRef v As Variant) As IDFSeries
End Function
' !=
Public Function neToSeries(ByRef v As Variant) As IDFSeries
End Function
' >
Public Function gtToSeries(ByRef v As Variant) As IDFSeries
End Function
' <
Public Function ltToSeries(ByRef v As Variant) As IDFSeries
End Function
' >=
Public Function geToSeries(ByRef v As Variant) As IDFSeries
End Function
' <=
Public Function leToSeries(ByRef v As Variant) As IDFSeries
End Function
' In()
Public Function inValsToSeries(ByRef vs As Variant) As IDFSeries
End Function
' between
Public Function betweenToSeries(ByRef left As Variant, ByRef right As Variant) As IDFSeries
End Function

'=============
' 生成 Series 切片，保存所有结果为 true 的数据的引用
'=============
' =
Public Function eqToSlice(ByRef v As Variant) As IDFSeries
End Function
' !=
Public Function neToSlice(ByRef v As Variant) As IDFSeries
End Function
' >
Public Function gtToSlice(ByRef v As Variant) As IDFSeries
End Function
' <
Public Function ltToSlice(ByRef v As Variant) As IDFSeries
End Function
' >=
Public Function geToSlice(ByRef v As Variant) As IDFSeries
End Function
' <=
Public Function leToSlice(ByRef v As Variant) As IDFSeries
End Function
' In()
Public Function inValsToSlice(ByRef vs As Variant) As IDFSeries
End Function
' between
Public Function betweenToSlice(ByRef left As Variant, ByRef right As Variant) As IDFSeries
End Function

'=============
' 检查某一索引的元素是否符合规则
'=============
'Public Function eqElem(ByRef index As Long, ByRef v As Variant) As Boolean
'End Function
'Public Function neElem(ByRef index As Long, ByRef v As Variant) As Boolean
'End Function
'Public Function gtElem(ByRef index As Long, ByRef v As Variant) As Boolean
'End Function
'Public Function ltElem(ByRef index As Long, ByRef v As Variant) As Boolean
'End Function
'Public Function geElem(ByRef index As Long, ByRef v As Variant) As Boolean
'End Function
'Public Function leElem(ByRef index As Long, ByRef v As Variant) As Boolean
'End Function
'Public Function inValsElem(ByRef index As Long, ByRef vs As Variant) As Boolean
'End Function
'Public Function betweenElem(ByRef index As Long, ByRef left As Variant, ByRef right As Variant) As Boolean
'End Function


'--------------------------------------------------
' 聚合运算
'--------------------------------------------------
' 返回 Series 中的最大值
'
' 如果 Series 中没有数据，则返回 Empty
' 如果当前 Series 的类型不支持 max 运算，则返回 Empty
'
Public Function max() As Variant
End Function

' 返回 Series 中的最小值
'
' 如果 Series 中没有数据，则返回 Empty
' 如果当前 Series 的类型不支持 min 运算，则返回 Empty
'
Public Function min() As Variant
End Function

'--------------------------------------------------
' 数据描述符
'--------------------------------------------------

' 获取某个数据的描述器
' 如果不存在，则返回 Nothing
'
' @param index 数据索引
' @optional-param needCreate 如果描述信息对象不存在是否需要进行创建。默认值=False
' @return IDFDescriptor 数据描述器
Public Function getDataDescriptor(ByRef index As Long, Optional ByRef needCreate As Boolean = False) As IDFDescriptor
End Function

'--------------------------------------------------
' 切片操作
'--------------------------------------------------
' 切片
' @optional-param start Long 起始位置
' @optional-param stop Long 终止位置(最终不会包含 stop 的索引)
' @optional-param step Long 步长
Public Function slice(Optional startIdx As Variant, Optional ByRef stopIdx As Variant, Optional ByRef step As Variant=1) As IDFSeries
End Function

' 使用指定索引创建切片
' 如果没有指定任何索引，则保留对所有数据的引用
' @param-array indexes 需要的真实索引
Public Function sliceByIndexes(ParamArray indexes() As Variant) As IDFSeries
End Function

' 使用指定索引数组创建切片
' 如果数组长度为 0，则保留对所有数据的引用
' @param indexes 需要的真实索引
Public Function sliceByIndexArray(ByRef indexes As Variant) As IDFSeries
End Function

'--------------------------------------------------
' 输出操作
'--------------------------------------------------

' 将 Series 中的内容输出到控制台
' 每个数据输出为一行
' Empty 将会以字符串 "@@EMPTY@@" 的形式输出
'
' @optional-param startIdx 输出的起始索引(包括这一行，从 0 开始)
'                          只支持 0、正数，如果输入了一个负数，则自动使用 0
'                          如果 startIdx > endIdx，则不输出任何数据
' @optional-param endIdx 输出的结束索引(包括这一行，从 0 开始)
'                          只支持 0、正数，如果输入了一个负数，则自动使用最大行索引
Public Sub printToConsole(Optional ByRef startIdx As Long = 0, _
    Optional ByRef endIdx As Long = -1)
End Sub
